home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / text / misc / mk3d1_1.lha / make3d / mk3d.doc < prev    next >
Encoding:
Text File  |  1995-03-03  |  14.0 KB  |  367 lines

  1. Document mk3d.doc
  2.  
  3.                 X       X       X       X       X       X     
  4.          8!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK
  5.          ry=8>p+Ry=8>p+Ry=>pj+Ry>p"jy>'[jyD5>[jyD$5>J[jy$5>J[jy
  6.          sM?&E/)_M?&E/)_M?E/)j_?E/@)?Ef@)]g?f@a)g??ff@)Og?ff@)O
  7.          yY-PM-e>Y-PM-e>Y-M-e>Y-M-Be-M-Bw"e-M-B"e)-MW-"e4)MW-"e
  8.          \7.\<.Ok7.\<.Ok7.<.+k7z<.p+z<,p+MHz,px+Hz{,gp+sH{,gp+s
  9.          2$!YZ,M|$!YZ,M|$!Z,pM|$Z,Sp$Zvjp$aXZjp$a[XZFjp$[XZFjp$
  10.          =D)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<q
  11.  
  12.  
  13. So, ya wanna make 3-d pictures using random stereo-whatsis technology, but
  14. using a text format so your BBS friends can enjoy it.  Well... this is the
  15. program for you.
  16.  
  17. Another fine product of The Cheese Olfactory Workshop.
  18.  
  19. 0. Introduction
  20. ---------------
  21.  
  22. Believe it or not, the basic idea of how to make these images has been
  23. around for several years.  According to _Magic Eye_ "A New Way of Looking
  24. at the World" (Copyright 1993 by N.E. Thing Enterprises, 
  25. ISBN: 0-8362-7006-1):
  26.  
  27.   "During the 1960s, Dr. Bella Julesz was the first to use
  28.    computer-generated 3D images made up of randomly placed dots to study
  29.    depth perception in human beings.  Because the dot pictures did not
  30.    contain any other information, like color or shapes, he could be sure that
  31.    when his subject saw the picture it was 3D only!"
  32.  
  33. Today, however, the technology seems to have gone crazy.  The book
  34. mentioned above contains several very nice images you can freak your eyes
  35. out over (the rose seems to be a particular favorite amongst most of the
  36. people I know).
  37.  
  38. Of course, trying to transmit something as detailed as one of THOSE
  39. pictures would require bundling the resulting stereogram as one of your
  40. favorite little file standards (pick a standard.. ANY standard) uuencoding
  41. the monster, then hoping the person on the other side has the software
  42. necessary to undo the mess.
  43.  
  44. Well.. that's fine.
  45.  
  46. This program doesn't come close to the detail you can get with a really
  47. nice program that actually uses real dots, instead of the synthetic ones
  48. we're going to be working with <snort>, but this software will let you
  49. transmit your little creation over E-mail, to a printer, through your
  50. cat's whiskers, and to Alpha-Centari.  In short, this program can create
  51. an ASCII 3-d image.  And we all know how interchangeable ASCII is.  Don't
  52. we?
  53.  
  54. 0.1. The Author
  55. ---------------
  56.  
  57. I don't have the slightest idea who originally wrote this program.  I
  58. caught a post off Usenet one day giving away some C code for a program
  59. called 'mk3d' (which, at least in name, I stuck with).  There was a binary
  60. with it called mk3d.exe, which meant, to me, that it had been compiled for
  61. MS-DOS <plegh>.
  62.  
  63. However, since I'm an anal-retentive programmer with too much time on my
  64. hands this vacation, and I don't feel like messing with my other pet
  65. projects, I decided to convert the C source to Amiga E, and add a bunch of
  66. nifty features (well, a few anyway).  After becoming bald, I managed to
  67. get the damned images to pop up the way they should.  E is a nice
  68. language, but I swear, trying to convert from C can be a damning
  69. experience.
  70.  
  71. As for myself, I'm merely a college student, 26 years old, working towards
  72. my Bachelor of Arts in Music (emphasis on Composition).  My senior project
  73. and its recital will be due by 5 Feb 95, by which time, hopefully, I will
  74. have released the .MID versions for the general public to scorn me over
  75. (my project has to be a composition, the recital of which will be
  76. performed by an Episcopal church choir I've been working with, and their
  77. organist.. pretty good performers, really).
  78.  
  79. The computers thing is something I picked up as a kid, and never really
  80. quite let go of.
  81.  
  82. UPDATE
  83.  
  84. Since I wrote the above I've aged a bit...  it's kind of
  85. creepy to look back.  I'm now 28 years old, and I'm in my
  86. final semester of college.  I have most of my composition
  87. written, I just need to write a little more and I will be
  88. finished.  I didn't quite meet my 5 Feb 95 date, but I had a
  89. recital of the music I had written of it anyway.  It went
  90. rather well.
  91.  
  92. BTW: I'm not really bald.. although my hair has thinned
  93. rather much towards the forehead.
  94.  
  95. I came back to this previously abandoned project because I
  96. needed to make a 3-d picture for a professor of philosophy.
  97. He wanted a stereogram of the word 'Truth' on it, because,
  98. according to him, "Not everyone can see the truth."
  99.  
  100. Of course, being the nice person I am, I have made both a
  101. 'Truth' and 'Lie' stereogram for the good professor, and I'm
  102. going to hand both of them to him at the same time, without
  103. telling him which is which; he hasn't been able to see
  104. stereograms yet <evil grin>.
  105.  
  106. Programming-wise, I'm much more interested in object
  107. programming techniques (particularly designing object
  108. systems, but that should be obvious to anyone working with
  109. such technology).  This project blatantly disregards such
  110. things, though.  In fact, as I look over the code, I'm
  111. somewhat horrified... but in an unconcerned kind of way.
  112. The cursed thing works now, and I'm ready to inflict it upon
  113. the world yet again.
  114.  
  115. 0.2. The Documentation
  116. ----------------------
  117.  
  118. The documentation for this program will hopefully be more detailed than
  119. the documentation I got for the MS-DOS version of mk3d.  I converted it over
  120. to AmigaGuide format for those who like that, and put in a whole bunch of
  121. BS (like what you are reading now) for those who are desperate to read
  122. stuff.
  123.  
  124. My e-mail address is jvanriper@uncavx.unca.edu (at least, until I finish
  125. school, which will probably be in May).
  126.  
  127. Special thanks to the author of text2guide (Stephan Sürken).  I wish I
  128. could kiss you.
  129.  
  130. 0.3. Distributability
  131. ---------------------
  132.  
  133. This software is freely distributable.  Even the source code has been
  134. released.  I am returning it to the public, since I got it from the
  135. public.
  136.  
  137. Heed my example.
  138.  
  139. 0.4. Disclaimers
  140. ----------------
  141.  
  142. All applicable disclaimers apply.  You didn't pay for this, so don't come
  143. screaming to me that you've overwritten your s:startup-sequence file with
  144. a stereogram, or that your big proposal that you've been slaving over for
  145. five years doesn't look very pretty in 3-d.  This software (as far as I
  146. can tell) is pretty stable, and should do its job provided you do your job
  147. in protecting your system from yourself and others.
  148.  
  149. In any event:
  150.  
  151. I, Joseph E. Van Riper III, and my company, the Cheese Olfactory Workshop,
  152. refuse to accept responsibility for the results of this program in any
  153. way, shape, or form.  Use of this program assumes responsibility on the
  154. user's part.
  155.  
  156. 1. The Program
  157. --------------
  158.  
  159. mk3d was originally written in C, and compiled for MS-DOS.  The code has
  160. been re-written for Amiga E, thus the binary is smaller and better than the
  161. original C counterpart's binary.
  162.  
  163. Since this was written in E, you don't need to worry about
  164. stacksize, and arguments are handled according to the
  165. standard AmigaDOS way (ReadArgs). As far as I know, this
  166. program will run on any Amiga system with at least Workbench
  167. version 2.04.
  168.  
  169. Original .EXE executable for MS-DOS:
  170.  
  171.   ------rw-d    18368  02-Sep-93 15:56:56  mk3d.exe
  172.  
  173. Amiga E executable for AmigaDOS (with many bells and whistles):
  174.  
  175.   ------rwed    11164  03-Mar-95 13:22:10  mk3d
  176.  
  177. Now.. given these stats, would you want an Amiga or an IBM-PC clone?
  178.  
  179. 1.1. Using mk3d
  180. ---------------
  181.  
  182. As with any program using ReadArgs, using a question mark as an argument
  183. will call up a template that might help you figure out the option you're
  184. looking for:
  185.  
  186. ---------------
  187.  
  188. > mk3d ?
  189.  
  190. IN=INPUT/A,OUT=OUTPUT,ERR=ERRORS/K,S=SIMPLE/N/K:
  191.  
  192. ---------------
  193.  
  194. Upon getting this, you can type another question mark for more detailed
  195. instructions:
  196.  
  197. ---------------
  198.  
  199. IN=INPUT/A,OUT=OUTPUT,ERR=ERRORS/K,S=SIMPLE/N/K: ?
  200.  
  201. Usage: mk3d IN "filename" [OUT "filename"] [ERR "filename"]
  202.             [S "number"]
  203.  
  204.  IN specifies a mandatory input file to read for a template.
  205. OUT specifies an optional output file to write.
  206. ERR specifies an optional error file to write (instead of stderr).
  207.   S specifies how simple the characters should be, by this chart:
  208.  
  209.       0 = Only uppercase characters
  210.       1 = Upper/lowercase characters
  211.       2 = Alphanumeric characters
  212.       3 = Alphanumeric characters with symbols (default)
  213.       4 = Anything printable via Topaz font
  214.  
  215. For information about the IN file's format, please, read mk3d.doc.
  216. NOTE: This program based on the same written for MS-DOS.
  217.       Modified somewhat heavily by Joseph E. Van Riper III
  218.       of the Cheese Olfactory Workshop.
  219.  
  220. ---------------
  221.  
  222. Generally, those instructions should be enough.
  223.  
  224. 1.1.1. INPUT
  225. ------------
  226.  
  227. Simply put, this refers to the file you want to read.  This parameter MUST
  228. be filled (although you don't have to actually type 'mk3d input fulu.stx'..
  229. you could just say 'mk3d fulu.stx').  If this parameter is missing, you'll
  230. see the extra helps screen and a little error message.  Read
  231. `The Input File' for more information.
  232.  
  233. 1.1.2. OUTPUT
  234. -------------
  235.  
  236. Simply put, this refers to the file you want to create.  This parameter is
  237. optional.. if it isn't filled, stdio is used (therefore, you can redirect
  238. the output).  This option doesn't really have to be spelled out.. it can
  239. be inferred as the name following the INPUT's filename (eg: you can type
  240. 'mk3d infile.stx outfile.asc' or 'mk3d infile.stx output outfile.asc').
  241.  
  242. 1.1.3. ERRORS
  243. -------------
  244.  
  245. NOTE: This part of the code was responsible for some nasty
  246. bugs.  I'm now using my StdErr port (available in the dev/e
  247. directory off Aminet, for those folks who are interested in
  248. such things).  Nobody (well, maybe one person, not sure)
  249. told me about this problem, and I never really caught it
  250. until two years passed and I had changed my setup
  251. considerably.  I couldn't get my program to work at all..
  252. which I thought was curious, so I diddled around and found
  253. the problem was in the cursed error port routine.  My
  254. current StdErr port is pretty stable, so I just rewrote
  255. everything to use it.
  256.  
  257. SO.. if you use 'ERR' it should work pretty well.
  258. Specifying 'NIL:' will cause the messages to be dropped in a
  259. trashbin somewhere in Io.
  260.  
  261. In any event, the current picture that the project is
  262. working on is sent to the standard error port.  You can
  263. significantly improve the speed of the program by specifying
  264. 'NIL:', but if you want to see the progress (and any error
  265. messages) then leave this alone.  You could specify a
  266. filename, and everything would be dumped into that file, but
  267. it might be sorta ugly (not sure).
  268.  
  269. 1.1.4. SIMPLE
  270. -------------
  271.  
  272. The SIMPLE parameter takes a number that will change the kind of
  273. characters that are used to generate the 3-d image.  If you wish to use
  274. this parameter, you MUST specify it (eg: 'mk3d infile.stx outfile.asc s 0'
  275. but not 'mk3d infile.stx outfile.asc 0' -- note also, 's' is a shortcut for
  276. SIMPLE).
  277.  
  278.  0 - Yields only uppercase characters.  This might be handy for those
  279. potentially existent people who are limited to modems that cannot output
  280. lowercase characters... or for similar reasons.  Very quick execution.
  281.  
  282.  1 - Yields upper/lowercase characters.  Any character in the alphabet,
  283. whether lowercase or uppercase, may be used to create the images.  Medium
  284. execution.
  285.  
  286.  2 - Yields Alphanumeric characters.  Upper and Lowercase characters of the
  287. alphabet, as well as numbers, can appear.  Slow execution.
  288.  
  289.  3 - Yields as 2, but may also have various punctuation characters.  Very
  290. quick execution. Also the default.
  291.  
  292. CHANGE:
  293.  
  294.  4 - Yields anything printable with a topaz font.  Very
  295.  flexible.  Tons 'o characters.  My personal favorite.
  296.  Slowish execution.
  297.  
  298. The more variety in characters, the less likely a chance for ambiguity in
  299. the imagine process.
  300.  
  301. NOTE: if you choose a number higher than 4, the program defaults to 3.
  302.  
  303. 2. The Input File
  304. -----------------
  305.  
  306. If you want to create your own images, you have to follow a special
  307. format.
  308.  
  309. The first line contains a number that represents the 'Gramwidth', or the
  310. maximum number of columns to go across the screen (to put it simply).  So,
  311. if you want something that can be viewed by most terminals, choose '79'. 
  312. If you have a compressed type on your printer, and you want to print out a
  313. large 3d image, you can figure out how many columns are available on the
  314. printer and use that.  Or, perhaps you have a nice font on your Amiga that
  315. you can use.
  316.  
  317. However, the Gramwidth must be between 1 and 512.  How someone thinks they
  318. could make a nice stereogram with only 3 columns is beyond me.
  319.  
  320. The next line is the Xdepth value.  This number comes between 5 and 64,
  321. and must be less than half of the Gramwidth.  Which, using math, means that
  322. you must really have a Gramwidth of 11 - 512... but I programmed this part
  323. according to the original code.  Sloppy programmers...
  324.  
  325. I haven't really played with the Xdepth values, but with a Gramwidth of 79
  326. its been recommended to use an Xdepth of 16.  I suspect this would control
  327. how much depth there is between layers.
  328.  
  329. After this, you can actually create the image you want.  The only
  330. characters that mk3d looks for, from this point on, are carriage returns
  331. (which, obviously, goes to the next line), and numbers from 1 to 9. 
  332. Everything else is considered 'background' characters, and ignored.
  333.  
  334. The characters 1-9 represent different layers.  A '1' will sit on the layer
  335. that's closest to the background, but just above it. '2' sits just above a
  336. '1'... and so on down the line, until '9' is the very top-most layer you
  337. can work with.  Therefore, careful readers will note that you have 10
  338. layers to work with!  That's as deep as it goes with this program.. sorry.
  339.  
  340. Examine the different input files included with the archive to get a feel
  341. for how the program works.
  342.  
  343. 3. History
  344. ----------
  345.  
  346. Version 1.1:
  347.  
  348. * Fixed the standard error port so it works MUCH better now.
  349.  
  350. * The program now actually WORKS.  Apparently, I was doing
  351. something funky with the stderr port that caused a lot of
  352. horrible problems.  Fixing the above caused the program to
  353. work properly.
  354.  
  355. * Changed the S 4 switch to allow the greatest number of
  356. printable characters, instead of just doing all 255
  357. characters in the table <shudder>.  This seems to be quite
  358. successful.
  359.  
  360. * Added the use of my stayrandom() routine for seeding the
  361. random number generator, instead of the rather simplistic
  362. (and not entirely effective) routine I used before.
  363.  
  364. Version 1.0:
  365.  
  366. * First released version.
  367.